feat(ai-tools): skills improvements + contributor skill tooling#3369
Open
dreamwasp wants to merge 11 commits into
Open
feat(ai-tools): skills improvements + contributor skill tooling#3369dreamwasp wants to merge 11 commits into
dreamwasp wants to merge 11 commits into
Conversation
|
View your CI Pipeline Execution ↗ for commit cca5497 ☁️ Nx Cloud last updated this comment at |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3369 +/- ##
==========================================
- Coverage 90.38% 89.89% -0.50%
==========================================
Files 398 270 -128
Lines 6576 5660 -916
Branches 2132 1909 -223
==========================================
- Hits 5944 5088 -856
+ Misses 624 564 -60
Partials 8 8
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Collaborator
|
📬 Published Alpha Packages:
|
Contributor
|
🚀 Styleguide deploy preview ready! Preview URL: https://6a340e7b6f73d939bd377f47--gamut-preview.netlify.app |
dreamwasp
changed the title
There was a problem hiding this comment.
Pull request overview
This PR expands the Gamut agent-tools ecosystem by adding new DataTable/DataList skills, improving existing skills and Storybook surfacing, introducing contributor-only skill syncing to Claude/Cursor, and enhancing DESIGN.md installation to be self-documenting with tests.
Changes:
- Added new
gamut-datatableandgamut-datalistskills and updated multiple existing skills for clearer triggers, cross-links, and guidance. - Introduced
local-skills/as the contributor-only skill source of truth plus a sync script and pre-commit automation to generate.claude/skills/and.cursor/rules/outputs. - Updated
installDesignMdto stamp a generated header (with version + rerun command) and added Node test-runner coverage wired into Nx.
Reviewed changes
Copilot reviewed 38 out of 40 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/sync-local-skills.mjs | New sync/check script to generate Claude/Cursor skill files from local-skills/. |
| packages/styleguide/src/lib/Typography/Text/Text.mdx | Adds Storybook callout pointing to /gamut-typography. |
| packages/styleguide/src/lib/Organisms/Lists & Tables/List/List.mdx | Adds Storybook callout pointing to /gamut-list. |
| packages/styleguide/src/lib/Organisms/Lists & Tables/DataTable/DataTable.mdx | Adds Storybook callout pointing to /gamut-datatable. |
| packages/styleguide/src/lib/Organisms/Lists & Tables/DataList/DataList.mdx | Adds Storybook callout pointing to /gamut-datalist. |
| packages/styleguide/src/lib/Organisms/GridForm/About.mdx | Adds Storybook callout pointing to /gamut-forms. |
| packages/styleguide/src/lib/Meta/AI Tooling/Gamut plugin/Best practices.mdx | Splits “Agent skills” into exported vs contributor-only; adds new skill entries. |
| packages/styleguide/src/lib/Foundations/ColorMode/ColorMode.mdx | Adds Storybook callout pointing to /gamut-color-mode. |
| packages/styleguide/src/lib/Atoms/Buttons/TextButton/TextButton.mdx | Adds Storybook callout pointing to /gamut-buttons. |
| packages/styleguide/src/lib/Atoms/Buttons/StrokeButton/StrokeButton.mdx | Adds Storybook callout pointing to /gamut-buttons. |
| packages/styleguide/src/lib/Atoms/Buttons/IconButton/IconButton.mdx | Adds Storybook callout pointing to /gamut-buttons. |
| packages/styleguide/src/lib/Atoms/Buttons/FillButton/FillButton.mdx | Adds Storybook callout pointing to /gamut-buttons. |
| packages/styleguide/src/lib/Atoms/Buttons/CTAButton/CTAButton.mdx | Adds Storybook callout pointing to /gamut-buttons. |
| packages/gamut/project.json | Adds test-bin target and wires it into test via dependsOn. |
| packages/gamut/package.json | Adds test:bin script for Node test runner. |
| packages/gamut/bin/lib/design.mjs | Updates DESIGN.md installer to prepend a generated header (version + rerun command). |
| packages/gamut/bin/tests/design.test.mjs | Adds Node test-runner coverage for installDesignMd. |
| packages/gamut/agent-tools/skills/gamut-typography/SKILL.md | Refines skill description scope and cross-reference. |
| packages/gamut/agent-tools/skills/gamut-theming/SKILL.md | Removes “Key principles” sediment section. |
| packages/gamut/agent-tools/skills/gamut-testing/SKILL.md | Fixes frontmatter formatting artifact. |
| packages/gamut/agent-tools/skills/gamut-system-props/SKILL.md | Updates description and fixes Best Practices link to Storybook URL. |
| packages/gamut/agent-tools/skills/gamut-style-utilities/SKILL.md | Fixes Best Practices link and removes “Key principles” sediment. |
| packages/gamut/agent-tools/skills/gamut-review/SKILL.md | Expands audit checks (SCSS/className, nested selectors, CSS vars, etc.) and remediation links. |
| packages/gamut/agent-tools/skills/gamut-list/SKILL.md | Adds DataTable/DataList cross-references and “reach higher-level component first” guidance. |
| packages/gamut/agent-tools/skills/gamut-layout/SKILL.md | Expands description to better surface responsive/layout triggers. |
| packages/gamut/agent-tools/skills/gamut-forms/SKILL.md | Normalizes description to “Use this skill when…” trigger framing. |
| packages/gamut/agent-tools/skills/gamut-datatable/SKILL.md | New skill documenting DataTable usage, props, ColumnConfig patterns, and examples. |
| packages/gamut/agent-tools/skills/gamut-datalist/SKILL.md | New skill documenting DataList usage, expansion/selection patterns, and examples. |
| packages/gamut/agent-tools/skills/gamut-color-mode/SKILL.md | Streamlines semantic alias documentation and links to canonical Storybook sources. |
| packages/gamut/agent-tools/skills/gamut-buttons/TOOLTIP_FOCUS.md | New focused doc for ToolTip lingering/focus management pattern. |
| packages/gamut/agent-tools/skills/gamut-buttons/SKILL.md | Replaces long inline section with pointer to TOOLTIP_FOCUS.md. |
| packages/gamut/agent-tools/skills/gamut-accessibility/SKILL.md | Refines description trigger framing. |
| packages/gamut/agent-tools/.cursor-plugin/plugin.json | Bumps plugin version. |
| packages/gamut/agent-tools/.claude-plugin/plugin.json | Bumps plugin version. |
| package.json | Adds sync-skills and sync-skills:watch scripts. |
| local-skills/gamut-create-skill/SKILL.md | Adds contributor-only “create skill” blueprint skill. |
| .nx/version-plans/version-plan-1780940298971.md | Adds version plan for a minor bump. |
| .husky/pre-commit | Runs sync-local-skills and stages generated outputs. |
| .cursor/rules/gamut-create-skill.mdc | Generated Cursor rule output for gamut-create-skill. |
| .claude/skills/gamut-create-skill/SKILL.md | Generated Claude skill output for gamut-create-skill. |
Comment on lines
+45
to
+52
| // Orphans: directories in .claude/skills/ with no matching local-skills/ source | ||
| const claudeEntries = await readdir(CLAUDE_SKILLS_DIR, { | ||
| withFileTypes: true, | ||
| }).catch(() => []); | ||
| const orphans = claudeEntries | ||
| .filter((e) => e.isDirectory() && !activeNames.has(e.name)) | ||
| .map((e) => e.name); | ||
|
|
Comment on lines
+100
to
+106
| const claudeDest = join(CLAUDE_SKILLS_DIR, name, 'SKILL.md'); | ||
| const cursorDest = join(CURSOR_RULES_DIR, `${name}.mdc`); | ||
| await mkdir(dirname(claudeDest), { recursive: true }); | ||
| await Promise.all([ | ||
| writeFile(claudeDest, content, 'utf8'), | ||
| writeFile(cursorDest, content, 'utf8'), | ||
| ]); |
Comment on lines
+75
to
+78
| | `header` | `string` | Column header label | | ||
| | `type` | `'header' \| 'control'` | `'header'` makes the column sticky when scrollable; `'control'` right-aligns and removes padding for action buttons | | ||
| | `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | Column width; omit to fit content | | ||
| | `fill` | `boolean` | Expands the column to fill remaining width | |
Comment on lines
+74
to
+77
| | `key` | `keyof Row` | Required; maps to a row data field | | ||
| | `header` | `string` | Column header label | | ||
| | `type` | `'header' \| 'control'` | `'header'` makes the column sticky when scrollable; `'control'` right-aligns and removes padding for action buttons | | ||
| | `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | Column width; omit to fit content | |
Comment on lines
+257
to
+265
| <div style={{ width: '280px' }}> | ||
| <DataList | ||
| disableContainerQuery | ||
| id="sidebar-list" | ||
| idKey="id" | ||
| rows={data} | ||
| columns={columns} | ||
| /> | ||
| </div> |
jakemhiller
reviewed
Jun 18, 2026
| SKILL.md ← canonical source | ||
| ``` | ||
|
|
||
| Contributor skills are synced automatically to `.claude/skills/` (Claude Code) and `.cursor/rules/` (Cursor) by the pre-commit hook. To sync manually: `yarn sync-skills`. To watch during development: `yarn sync-skills:watch`. |
Contributor
Author
There was a problem hiding this comment.
good catch - claude i CONVINCED cursor can't use skills. i'll fix
LinKCoding
approved these changes
Jun 22, 2026
LinKCoding
left a comment
LinKCoding
left a comment
Contributor
There was a problem hiding this comment.
I like the guidance --
I didn't check against all the technical writing, but looked after the styling and overall layout and it LGTM!
I have some thoughts on consistency for how files are linked to. And some Callout text could be updated to style the "code".
🔥 🔥🔥
| Full tables: Storybook theme pages or audit with [`gamut-review`](../gamut-review/SKILL.md) Appendix A/B for hex triage. | ||
| ## Semantic aliases | ||
|
|
||
| These tokens describe roles; actual colors come from the active theme + ColorMode. Full alias tables: [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — and per-theme breakdowns at [Core](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-theme--docs) · [Admin](https://gamut.codecademy.com/?path=/docs-foundations-theme-admin-theme--docs) · [Platform](https://gamut.codecademy.com/?path=/docs-foundations-theme-platform-theme--docs) · [Percipio](https://gamut.codecademy.com/?path=/docs-foundations-theme-percipio-theme--docs) · [LX Studio](https://gamut.codecademy.com/?path=/docs-foundations-theme-lx-studio-theme--docs). Source: [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes). |
Contributor
There was a problem hiding this comment.
Rather than link to the sites, would it be ok to link to the local markdown files?
|
|
||
| Item-focused list for managing, engaging with, and expanding individual rows. Use when users interact with items — opening details, selecting for bulk actions, or viewing expanded layouts — rather than scanning and comparing data across rows. | ||
|
|
||
| Source: `@codecademy/gamut` — [DataList.tsx](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/DataList/DataList.tsx) |
Contributor
There was a problem hiding this comment.
Same note here about linking to the local file
Contributor
There was a problem hiding this comment.
I'll stop leaving notes re: path
maybe something the robot can just audit
| --- | ||
| name: gamut-system-props | ||
| description: Use this skill when building or refactoring styled Gamut components that need layout, spacing, color, border, background, typography, positioning, grid, flex, shadow, list styles, or responsive values from @codecademy/gamut-styles — including composing system prop groups with variance. | ||
| description: 'Use this skill when composing system prop groups (`system.*`) on styled components, selecting which group covers a CSS property, or building responsive props with `variance.compose()` — not for `css()`, `variant()`, or `states()` (see gamut-style-utilities).' |
Contributor
There was a problem hiding this comment.
Nit: the other descriptions aren't wrapped in quotes
|
|
||
| <ComponentHeader {...parameters} /> | ||
|
|
||
| <Callout text="Use the /gamut-buttons skill in Cursor or Claude Code for AI-assisted guidance on button selection, variants, disabled patterns, and ToolTip focus management." /> |
Contributor
There was a problem hiding this comment.
Suggested change
| <Callout text="Use the /gamut-buttons skill in Cursor or Claude Code for AI-assisted guidance on button selection, variants, disabled patterns, and ToolTip focus management." /> | |
| <Callout | |
| text={ | |
| <> | |
| Use the <code>/gamut-buttons<code> skill in Cursor or Claude Code for AI-assisted guidance on button selection, variants, disabled patterns, and ToolTip focus management." | |
| </> | |
| } | |
| /> |
Contributor
There was a problem hiding this comment.
totally a stylistic thing, but feels cleaner
|
|
||
| **Storybook MDX** | ||
|
|
||
| Read the component's MDX documentation page: |
Contributor
There was a problem hiding this comment.
leaving this as a reference -- there's a few instances where the agent is being prompted to fetch from the SB site instead of a local file.
I'd assume reading locally is faster
| @@ -0,0 +1,263 @@ | |||
| --- | |||
Contributor
There was a problem hiding this comment.
Curious, are these files automatically sync'd + duped?
or are these manual?
In Front, when I did the a11y skill, I saw the files being automatically duped into a .claude folder (see: https://github.skillsoft.com/federated-front/front/pull/13922/files)
I'm guessing the .claude folder was gitignored too
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Expands the Gamut agent-tools skill set, audits and improves all existing skills, adds a contributor-only skills infrastructure, and improves the
DESIGN.mdgeneration tooling.New skills
gamut-datatable— full skill forDataTable: when to use, props,ColumnConfig,useLocalQuery, row action menus withPopoverContainer, empty/loading states, color mode, and container queriesgamut-datalist— full skill forDataList: same coverage plusvariant(default/card), expandable rows (expandedContent/onRowExpand), row selection (onRowSelect/hideSelectAll), and combined expansion + selection patternsUpdated skills
gamut-list— addedDataTable/DataListcross-references and a "reach for a higher-level component first" callout at the top of "When to use List"gamut-buttons— moved "Focus management — buttons with ToolTip" toTOOLTIP_FOCUS.md(progressive disclosure); inline section replaced with a 3-line context pointergamut-layout— expanded frontmatter description to surface the skill for media-query / responsive-layout queries,useWindowSize/useBreakpointhooks, and mobile-first patternsgamut-review— three new checks:classNameon Gamut components${GamutComponent}child selectors)var(--darkNeutralColor)etc.)@codecademy/gamut-kitpackage recognition,StyleProps+states()/variant()validation,jest.mock(GamutProvider)warning, expanded remediation skill linksSkill quality audit (applied
writing-great-skillsframework across all skills)gamut-forms,gamut-accessibility,gamut-review,gamut-layout,gamut-typography,gamut-system-props## Key principlessediment fromgamut-theming,gamut-style-utilities,gamut-system-propsgamut-style-utilitiesandgamut-system-propsgamut-color-mode: merged duplicate decision guides; replaced exhaustive semantic alias token tables (~60 lines) with a Storybook pointer; removed Core hex illustration section (duplicatesgamut-reviewAppendix B)gamut-datatable: replaced duplicateemptyMessageJSX example with a pointer togamut-datalistgamut-testing: removed double---formatting artifactContributor tooling
local-skills/directory — canonical source for contributor-only skills, never exported viagamut plugin installscripts/sync-local-skills.mjs— syncslocal-skills/→.claude/skills/(Claude Code) and.cursor/rules/(Cursor);--checkmode for CI; auto-cleans orphaned generated files when a skill is removedyarn sync-skills/yarn sync-skills:watchfor manual and dev usegamut-create-skillmoved from exported skills tolocal-skills/— contributor-only blueprint playbook, now includes a/writing-great-skillsreview step in the consistency checklistdesign.mjstoolinginstallDesignMdnow stamps a<!-- Generated by @codecademy/gamut@{version} … -->header at the top ofDESIGN.mdinstead of a plaincopyFile— includes the re-run command so the file is self-documentingbin/__tests__/design.test.mjs(Node built-in test runner, no Jest dependency) covers: version stamp, theme alias in comment,--forceguard, fallback to"unknown"whenpackage.jsonis absent, source file unchangedtest:binnpm script +test-binNX task wired as a dependency of the maintesttargetPR Checklist
minorbump —.nx/version-plans/version-plan-1780940298971.md)bin/__tests__/design.test.mjs)Testing Instructions
Column size="content"story renders and shows misaligned header/data widths as expected/gamut-datatableor/gamut-datalistin a Claude Code session — verify the skills surface and contain accurate prop tables and examples/gamut-list— verify the "reach for a higher-level component first" callout appears at the top of "When to use List"/gamut-buttons— verify the ToolTip focus section is a 3-line pointer toTOOLTIP_FOCUS.md, and thatTOOLTIP_FOCUS.mdcontains the full pattern/gamut-reviewon a repo with SCSS imports — verify Checks 3b and 3c appear in the outputyarn sync-skillsfrom the repo root — verify it outputssynced: gamut-create-skilland that.claude/skills/gamut-create-skill/SKILL.mdand.cursor/rules/gamut-create-skill.mdcare up to datenode scripts/sync-local-skills.mjs --check— verify it exits 0 with "All generated skill files are up to date"yarn test:bin(ornx run @codecademy/gamut:test-bin) — all 6installDesignMdtests should passgamut plugin install --theme corein a fresh directory — verifyDESIGN.mdis created with a<!-- Generated by @codecademy/gamut@x.y.z -->header--force— verify it errors with "already exists"--force— verify it overwrites cleanlyPR Links and Envs